# Peat Accumulation & Carbon Dataset — Dataverse README

**Project:** Carbon accumulation project and paper  
**Maintainer:** Juan C. Benavides Duque (Pontificia Universidad Javeriana)  
**Contact:** <add email>  
**DOI:** <Dataverse DOI will appear here once published>  
**Version:** 1.0.0  
**Last updated:** <YYYY‑MM‑DD>

---

## Overview
This Dataverse deposit contains: (i) per‑core Bayesian ²¹⁰Pb age–depth runs using **PLUM** with optional ¹⁴C tie points, (ii) harmonized tabular data for age–depth, peat and carbon accumulation, bulk density, site metadata, and climate (Tavg/Tmin; anomalies and absolutes), (iii) R scripts to fully reproduce analyses and figures, and (iv) geospatial inputs/outputs used to build the maps. A number of files live under **`Geographic/`** (with a `derived/` subfolder for outputs), and per‑core chronology inputs/outputs live under **`Plum_runs/`**.

---

## Directory Structure (as deposited)
```
.
├── README.md
├── AGE_DEPTH_with_Tanoms_and_Tabs.csv
├── AGE_DEPTH_with_Tanoms_Tabs_CAR_PAR_PRE.csv
├── AGES_MASTER_all_cores.csv
├── AGES_MASTER_with_CARBON_bd_and_Cgm2.csv
├── cores.csv
├── CORESASH.csv
├── cores_with_worldclim_tavg_tmin.csv
├── TAVG_annual_by_core.csv
├── TMIN_annual_by_core.csv
│
├── Geographic/                      # Geospatial inputs (see below)
│   ├── derived/                      # Outputs from geographic analysis (maps, rasters, tiles)
│   └── ...                           # e.g., core points, boundaries, paramo polygons
│
├── Plum_runs/                        # One folder per core (PLUM inputs/outputs)
│   └── <core_id>/
│       ├── pb210.csv                 # ²¹⁰Pb measurements by depth
│       ├── c14.csv                   # ¹⁴C tie points (optional)
│       ├── plum_config.yml           # PLUM priors/settings
│       ├── plum_output.rds           # Full PLUM object (posterior)
│       └── MANIFEST.json             # Checksums, script commit, run timestamp
│
├── Plum_runs.zip                     # Zip archive backup of Plum_runs (optional; not required)
│
├── fig01_map_vertical.pdf            # Map figure (may also live under Geographic/derived/)
├── Fig04 PA_CA_heatmaps_Tmeananom_vs_elev.pdf
│
├── carbonaccum.r
├── climate data prep cores.r
├── disturbance.r
├── effect size and plots.r
├── extract_climate.r
├── fig1 map.r
├── heatmap.r
├── Pb210 activity rplum.r
└── wordclim_abs_temp.r
```

> **Note:** Before publication, prefer moving figure exports under **`Geographic/derived/`** (maps) and/or a `docs/figures/` folder. Keep **`Plum_runs.zip`** out of the public deposit if redundant with `Plum_runs/`.

---

## File & Table Descriptions

### Age–depth & accumulation tables (root)
- **`AGE_DEPTH_with_Tanoms_and_Tabs.csv`**  
  Layer‑level age–depth summaries with *temperature anomalies* (Tanom) and *absolute temperature* fields (Tabs). Contains core ID, depth (cm), median/quantile ages (cal AD/yr), and matched climate variables by layer.

- **`AGE_DEPTH_with_Tanoms_Tabs_CAR_PAR_PRE.csv`**  
  As above, plus derived **C**arbon **A**ccumulation **R**ate (CAR), **P**eat **A**ccumulation **R**ate (PAR), and precipitation (**PRE**) variables, typically aggregated in time bins used in the paper.

- **`AGES_MASTER_all_cores.csv`**  
  Master age–depth posterior summaries across all cores (harmonized). Use this as the canonical age–depth table for cross‑site comparisons.

- **`AGES_MASTER_with_CARBON_bd_and_Cgm2.csv`**  
  Master table joined with carbon (%) / bulk density (g cm⁻³) and areal carbon metrics (e.g., g C m⁻² for slices/intervals). Downstream scripts derive CAR from these fields.

- **`cores.csv`**  
  Base site metadata and core IDs (WGS84 coords, elevation, peatland type, disturbance class, collection year, etc.).

- **`CORESASH.csv`**  
  Alternate/augmented site metadata used in mapping workflows (e.g., symbolization attributes). Contents mirror `cores.csv` but may include additional cartographic fields.

- **`cores_with_worldclim_tavg_tmin.csv`**  
  Site metadata joined with WorldClim‑derived **Tavg** and **Tmin** (absolute climatologies) used for covariates and for building anomalies.

- **`TAVG_annual_by_core.csv`, `TMIN_annual_by_core.csv`**  
  Annual time‑series per core of Tavg/Tmin (absolute). The anomaly baseline and smoothing windows are defined in the climate scripts below.

### Per‑core chronology folders — `Plum_runs/`
Each subfolder `Plum_runs/<core_id>/` contains the inputs/outputs to reproduce a PLUM run.

**Required files**
- `pb210.csv` — ²¹⁰Pb measurements by slice. Expected columns: `core_id`, `depth_cm`, `thickness_cm` (optional), `pb210_total_Bq_kg`, `pb210_supported_Bq_kg` *or* `pb210_excess_Bq_kg`, `activity_se_Bq_kg` (per‑slice uncertainty), `lab_id`, `method`, `comments`.
- `plum_config.yml` — Priors and MCMC settings (supported activity prior, accumulation/memory priors, iterations, burn‑in, thinning, calibration curve, seed).

**Optional files**
- `c14.csv` — ¹⁴C tie points (depth top/bottom, lab ID, age ¹⁴C yr BP ±1σ, F14C if available, δ¹³C, material, pretreatment, comments).

**Outputs**
- `plum_output.rds` — Serialized PLUM model fit (full posterior).  
- `MANIFEST.json` — Checksums, script commit/tag, run start/finish timestamps, and R session info.

### Geospatial data — `Geographic/`
- **Inputs (typical):** core point layers, country/department boundaries, Andes extent, páramo polygons, DEM‑derived layers used for profiling/elevation. Projection: WGS84 (EPSG:4326) unless otherwise noted.  
- **`Geographic/derived/` (outputs):** cartographic products and intermediate rasters used to build figures (e.g., tiled basemaps, masked polygons, core symbol layers). Final map PDFs/PNGs (e.g., `fig01_map_vertical.pdf`) may be stored here.

> If coordinates are sensitive, round to ≤ 3 decimals and document the generalization in `metadata/methods.md`.

### Figures (root)
- **`fig01_map_vertical.pdf`** — Main study‑area map (vertical layout).  
- **`Fig04 PA_CA_heatmaps_Tmeananom_vs_elev.pdf`** — Heatmaps of peat/carbon accumulation vs temperature anomaly across elevation classes.

### R scripts (root)
- **`Pb210 activity rplum.r`** — Prepares ²¹⁰Pb inputs and runs PLUM per core, writing outputs into `Plum_runs/<core_id>/` and appending age–depth summaries to master tables.
- **`carbonaccum.r`** — Computes peat and carbon accumulation metrics (PAR, CAR) from age–depth outputs and carbon/bulk‑density inputs; writes `AGE_DEPTH_with_Tanoms_Tabs_CAR_PAR_PRE.csv`.
- **`extract_climate.r`** — Extracts annual Tavg/Tmin by core from climate data sources and writes `TAVG_annual_by_core.csv` / `TMIN_annual_by_core.csv`.
- **`wordclim_abs_temp.r`** — Derives WorldClim absolute temperature covariates per site; feeds into `cores_with_worldclim_tavg_tmin.csv`.
- **`climate data prep cores.r`** — Joins absolute climate with age–depth layers and computes anomalies (baseline defined in script; commonly 1970–2000), generating the `Tanom` and `Tabs` fields.
- **`heatmap.r`** — Generates heatmaps relating accumulation rates to climate anomalies; outputs include `Fig04 ... heatmaps ... .pdf`.
- **`effect size and plots.r`** — Computes effect sizes for climate vs accumulation relationships; produces figure panels used in the paper.
- **`disturbance.r`** — Encodes and analyzes disturbance classes and their effects on accumulation rates and age–depth behaviour.
- **`fig1 map.r`** — Builds the main study‑area map using layers in `Geographic/`; outputs to `Geographic/derived/` and/or `fig01_map_vertical.pdf`.

> **OS paths used in scripts:** variables like `pcdir` and `macdir` point to Windows/Mac base directories and are only for local convenience. All file paths in the deposit are relative.

---

## Reproducibility & Workflow
1. Install R (≥ 4.3). Required packages include: `readr`, `dplyr`, `tidyr`, `purrr`, `ggplot2`, `mgcv`, `plum`, `rjags` (if used), `yaml`, `jsonlite`, `sf`, `terra` (for maps). If you use **renv**, include `renv.lock` and run `renv::restore()`.
2. **Chronologies:** Configure each core under `Plum_runs/<core_id>/plum_config.yml`, then run **`Pb210 activity rplum.r`**.
3. **Climate:** Run **`extract_climate.r`** and **`wordclim_abs_temp.r`**; then **`climate data prep cores.r`** to compute anomalies and join with layers.
4. **Accumulation:** Run **`carbonaccum.r`** to compute PAR/CAR and precipitation‑linked fields.
5. **Figures & effect sizes:** Run **`heatmap.r`**, **`effect size and plots.r`**, and **`fig1 map.r`**. Map outputs should be placed under `Geographic/derived/`.

All generated tables (e.g., `AGE_DEPTH_with_Tanoms_Tabs_CAR_PAR_PRE.csv`) are **derived products**; do not edit manually.

---

## QC & Validation
- Scripts validate plausible ranges (no negative activities; densities within 0.02–1.5 g cm⁻³; coordinates in valid ranges). Failing rows are flagged in QC messages/logs.
- Excluded ¹⁴C tie‑points must be justified in `c14.csv > comments` and reflected in manuscript methods.
- Each `Plum_runs/<core_id>/MANIFEST.json` should store checksums of inputs/outputs and script commit/timestamp.

---

## Licensing & Citation
- **Data:** CC BY 4.0 (recommended).  
- **Code:** MIT License.  

**Dataset citation (example):**  
Benavides Duque, J. C., et al. (<year>). *Peat ²¹⁰Pb/¹⁴C chronologies, carbon & bulk density, climate and site metadata (Andes & Amazonia)* [Dataset]. Dataverse. https://doi.org/<doi>

**Software/methods:**  
Aquino‑López, M. A., Blaauw, M., Christen, J. A., & Sanderson, N. C. (2018). A Bayesian approach to 210Pb dating of sediments. *Quaternary Geochronology*, 47, 85–97.  
Blaauw, M., & Christen, J. A. (2011). Flexible paleoclimate age‑depth models using an autoregressive gamma process. *Bayesian Analysis*, 6(3), 457–474.

---

## Pre‑publish Checklist
- [ ] All CSVs are UTF‑8 with `,` as delimiter and `.` as decimal point  
- [ ] `Plum_runs/` contains one folder per core with `pb210.csv`, optional `c14.csv`, `plum_config.yml`, `plum_output.rds`, and `MANIFEST.json`  
- [ ] Figures moved to `Geographic/derived/` (or `docs/figures/`)  
- [ ] Zip archives removed if redundant (e.g., `Plum_runs.zip`)  
- [ ] README contact, DOI, and date fields completed  
- [ ] Sensitive coordinates reviewed and generalized if needed

